.TH LIBPFM 3  "November, 2002" "" "Linux Programmer's Manual"
.SH NAME
pfm_get_impl_pmcs, pfm_get_impl_pmds, pfm_get_impl_counters \- return bitmask of implemented PMU registers
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.sp
.BI "int pfm_get_impl_pmcs(unsigned long " impl_pmcs "[4]);"
.BI "int pfm_get_impl_pmds(unsigned long " impl_pmds "[4]);"
.BI "int pfm_get_impl_counters(unsigned long " impl_counts "[4]);"
.BI "int pfm_get_num_counters(void);"
.sp
.SH DESCRIPTION
The first three functions returns a bitmask indicating which registers
are implemented on the host PMU. The number of implemented PMU
register can vary from one implementation of the architecture to another.
The architecture requires a certain set of PMU registers to be implemented,
namely PMC0-PMC7 and PMD4-PMD7 out of a maximum of 256 PMDs and 256 PMCs.
.sp
This call must be made after the library has been successfully initialized. 
Because a maximum of 256 PMD and 256 PMC registers can be implemented, the 
functions use an array of 4 long integers as argument. Each of the 256 bits 
spread across all 4 elements represents one register. Typically only the first 
element of the array is relevant.
.sp
The \fBpfm_get_impl_pmcs\fR returns the bitmask of implemented PMCS.
The \fBpfm_get_impl_pmds\fR returns the bitmask of implemented PMDS.
The \fBpfm_get_impl_counters\fR returns a bitmask of the PMD/PMC pairs
which can be used as counters. PMU registers can be used for very
different purposes: control, counting, buffers. The counters are used
to accumulate the number of occurrences of events and are typically the
one used by monitoring tools. The architecture dictates that at least
4 pairs exist and that they must be in PMC4/PMD4 through PMC7/PMD7. 
The corresponding bits are guaranteed to be set in all three returned bitmasks.

The \fRpfm_num_counters\fR function returns the number of counters
implemented by the host PMU. The same results can be obtained by counting
the number of bits set in the bitmask returned by \fBpfm_get_impl_counters\fR.

.SH RETURN
The function returns whether or not it was successful.
A return value of \fBPFMLIB_SUCCESS\fR indicates success, 
otherwise the value is the error code.
.SH ERRORS
.B PFMLIB_ERR_NOINIT
the library has not been initialized properly.
.SH AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
.PP
